Doc: clarify priority of lint level sources #142021

HamidrezaSK · 2025-06-04T09:59:01Z

This updates the rustc book to clearly document how conflicting lint configurations are resolved across different sources, including command-line flags, crate-level attributes, in-line attributes, and --cap-lints.

It also explains the special behavior of forbid and force_warn.

Fixes #124088

rustbot · 2025-06-04T09:59:07Z

r? @ehuss

rustbot has assigned @ehuss.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

jieyouxu · 2025-06-04T10:22:42Z

src/doc/rustc/src/lints/levels.md

+
+## Priority of Lint Level Sources
+
+Rust allows setting lint levels (`allow`, `warn`, `deny`, etc.) through various sources: directly in the code, via command-line flags, or through global compiler configuration. When these sources conflict, the compiler follows a well-defined priority order to determine which setting takes effect.


Some general remarks (I don't have bandwidth to take over review for this ATM):

I wonder if we should explicitly delineate between lint level control mechanisms which are compiler-only, versus those part of the language (such as in-source lint level attributes).

I'm not so sure the priority order is well-defined. See Support overriding warnings level for a specific lint via command line #113307 (comment).

Note that the ordering of compiler flags can matter! Some flags are "commutative" (in terms of observable final behavior) with respect to each other IIRC, while some flags aren't.

(Unstable, not suitable for stable rustc book) there's also the --crate-attr flag, which can somewhat blur the line between compiler vs language.

Thanks for the feedback! I took a closer look and I think you're right. If that's the case, it might be best to just document the ordering for in-source lint level attributes, where the behavior is straightforward: the closer attribute takes precedence.

ehuss

Thanks!

Looks like there is a CI error that needs to be resolved.

ehuss · 2025-06-05T13:45:09Z

src/doc/rustc/src/lints/levels.md

+
+## Priority of Lint Level Sources
+
+Rust allows setting lint levels (`allow`, `warn`, `deny`, etc.) through various sources: directly in the code, via command-line flags, or through global compiler configuration. When these sources conflict, the compiler follows a well-defined priority order to determine which setting takes effect.


What is a "global compiler configuration"?

Poor wording on my side, I meant options in the .cargo file, which is the same as CLI options, so I removed this part.

ehuss · 2025-06-05T13:46:07Z

src/doc/rustc/src/lints/levels.md

+
+Rust allows setting lint levels (`allow`, `warn`, `deny`, etc.) through various sources: directly in the code, via command-line flags, or through global compiler configuration. When these sources conflict, the compiler follows a well-defined priority order to determine which setting takes effect.
+
+This section explains how Rust resolves conflicts between **different sources of lint configuration**, rather than between the lint levels themselves.


Wording nit:

Suggested change

This section explains how Rust resolves conflicts between **different sources of lint configuration**, rather than between the lint levels themselves.

This section explains how conflicts are resolved between **different sources of lint configuration**, rather than between the lint levels themselves.

ehuss · 2025-06-05T13:47:10Z

src/doc/rustc/src/lints/levels.md

+
+This section explains how Rust resolves conflicts between **different sources of lint configuration**, rather than between the lint levels themselves.
+
+### Priority of Sources (Highest to Lowest)


Usually use sentence case for section titles.

Suggested change

### Priority of Sources (Highest to Lowest)

### Priority of sources (highest to lowest)

ehuss · 2025-06-05T14:11:08Z

src/doc/rustc/src/lints/levels.md

+in-line attributes (#[...]) >
+crate-level attributes (#![...]) >


I think the way this is presented is possibly confusing. The language doesn't differentiate between inner and outer attributes for lint levels. It just so happens that crate-level can only be specified by an inner attribute. But inner attributes can show up in many places. I would probably just say "attributes" here, since attributes just create an AST-hierarchy with the most-specific taking precedence.

ehuss · 2025-06-05T14:12:50Z

src/doc/rustc/src/lints/levels.md

+command-line flags (-A, -W, -D)
+```
+
+### Special Cases


Suggested change

### Special Cases

### Special case priorities

ehuss · 2025-06-05T14:15:54Z

src/doc/rustc/src/lints/levels.md

+
+### Special Cases
+
+The special levels `forbid(lint)` and `force_warn(lint)` take precedence over normal configurations **regardless of where they are set**.


The use of parentheses looks a little strange here to me, since force_warn(lint) isn't a valid syntax anywhere. How about just something like this?

Suggested change

The special levels `forbid(lint)` and `force_warn(lint)` take precedence over normal configurations **regardless of where they are set**.

The special levels forbid and force-warn take precedence over normal configurations **regardless of where they are set**.

I don't know what "normal configurations" are.

Also, this doesn't seem quite accurate to me. cap-lints takes precedence over forbid.
And in a sense it does matter where forbid is set, since it applies only to the AST-hierarchy below where it is set.

force-warn can only be set in one place (the CLI), though I'm not sure if this is trying to convey something about the order of CLI arguments?

This doesn't say how forbid and force-warn interact with one another.

It is a bit confusing for me. As far as I understood, for allow, deny, and warn whoever has the most-specific scope takes precedence. However, it is the opposite case for forbid and force-warn.

Even the ordering in the cli options, as mentioned in the book, for -A, -D, and -W which ever option comes last, takes place, but for --force-warn and -F which ever option comes first, takes place.

This updates the rustc book to clearly document how conflicting lint configurations are resolved across different sources, including command-line flags, crate-level attributes, in-line attributes, and `--cap-lints`. It also explains the special behavior of `forbid` and `force_warn`.

rustbot assigned ehuss Jun 4, 2025

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 4, 2025

This comment has been minimized.

Sign in to view

jieyouxu reviewed Jun 4, 2025

View reviewed changes

ehuss reviewed Jun 5, 2025

View reviewed changes

HamidrezaSK force-pushed the fix-lint-precedence-doc branch from bb04e82 to 6e8d426 Compare June 6, 2025 20:53

This comment has been minimized.

Sign in to view

HamidrezaSK force-pushed the fix-lint-precedence-doc branch from 6e8d426 to 3cf81db Compare June 6, 2025 21:49

This comment has been minimized.

Sign in to view

HamidrezaSK force-pushed the fix-lint-precedence-doc branch from 3cf81db to d6603df Compare June 6, 2025 22:32

This comment has been minimized.

Sign in to view

HamidrezaSK force-pushed the fix-lint-precedence-doc branch from d6603df to e097fd1 Compare June 7, 2025 08:17

HamidrezaSK requested review from ehuss and jieyouxu June 11, 2025 13:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Doc: clarify priority of lint level sources #142021

Doc: clarify priority of lint level sources #142021

HamidrezaSK commented Jun 4, 2025 •

edited by rustbot

Loading

Uh oh!

rustbot commented Jun 4, 2025

Uh oh!

This comment has been minimized.

jieyouxu Jun 4, 2025 •

edited

Loading

Uh oh!

HamidrezaSK Jun 4, 2025

Uh oh!

ehuss left a comment

Uh oh!

ehuss Jun 5, 2025

Uh oh!

HamidrezaSK Jun 6, 2025

Uh oh!

ehuss Jun 5, 2025

Uh oh!

ehuss Jun 5, 2025

Uh oh!

ehuss Jun 5, 2025

Uh oh!

ehuss Jun 5, 2025

Uh oh!

ehuss Jun 5, 2025

Uh oh!

HamidrezaSK Jun 6, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Uh oh!


		## Priority of Lint Level Sources

		Rust allows setting lint levels (`allow`, `warn`, `deny`, etc.) through various sources: directly in the code, via command-line flags, or through global compiler configuration. When these sources conflict, the compiler follows a well-defined priority order to determine which setting takes effect.


		Rust allows setting lint levels (`allow`, `warn`, `deny`, etc.) through various sources: directly in the code, via command-line flags, or through global compiler configuration. When these sources conflict, the compiler follows a well-defined priority order to determine which setting takes effect.

		This section explains how Rust resolves conflicts between different sources of lint configuration, rather than between the lint levels themselves.

	This section explains how Rust resolves conflicts between different sources of lint configuration, rather than between the lint levels themselves.
	This section explains how conflicts are resolved between different sources of lint configuration, rather than between the lint levels themselves.


		This section explains how Rust resolves conflicts between different sources of lint configuration, rather than between the lint levels themselves.

		### Priority of Sources (Highest to Lowest)

		in-line attributes (#[...]) >
		crate-level attributes (#![...]) >


		### Special Cases

		The special levels `forbid(lint)` and `force_warn(lint)` take precedence over normal configurations regardless of where they are set.

	The special levels `forbid(lint)` and `force_warn(lint)` take precedence over normal configurations regardless of where they are set.
	The special levels forbid and force-warn take precedence over normal configurations regardless of where they are set.

Doc: clarify priority of lint level sources #142021

Are you sure you want to change the base?

Doc: clarify priority of lint level sources #142021

Conversation

HamidrezaSK commented Jun 4, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented Jun 4, 2025

Uh oh!

This comment has been minimized.

jieyouxu Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ehuss left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Uh oh!

HamidrezaSK commented Jun 4, 2025 •

edited by rustbot

Loading

jieyouxu Jun 4, 2025 •

edited

Loading